home *** CD-ROM | disk | FTP | other *** search
/ Aminet 12 / Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso / Aminet / misc / edu / Calgor.lha / Cal / Docs / Manual < prev    next >
Encoding:
Text File  |  1996-03-22  |  10.7 KB  |  366 lines
  1. 1.0 Introduction
  2.  
  3. Welcome to the animation programming manual.  All the animation
  4. 'c'functions are detailed so that you can dictate and change the
  5. behaviour of the animation systems five user modules.
  6.  
  7. To program your own algorithms you
  8.  
  9. 1).  Include the source (including the animation functions) in
  10.      one of the user#.c modules
  11. 2).  Compile Project
  12. 3).  Run Compiled Program
  13.  
  14. 1.1 Labelling Line Numbers
  15.  
  16. All the animation functions  start with an 'a_' and have an
  17. integer parameter (the last one).  This parameter indicates to
  18. the player which line of code the function is referring too.  I
  19. call this parameter the highlight reference (HLF).
  20.  
  21. In the process of altering an algorithm, it is useful to label
  22. the line numbers with their reference number (starting at 0),
  23. this will help you to give the correct HLF.
  24.  
  25. E.g.
  26.  
  27. #include<stdio.h>
  28. #include<anim.h>
  29.  
  30. /* 000 */ void sel_control(void);
  31. /* 001 */ void selection(int [],int);
  32.  
  33. /* 002 */ void sel_control(void){
  34. /* 003 */   int b[7]={ 12, 13, 11, 9, 14, 15, 16};
  35.             a_func("sel_control",2);
  36.             a_irayini(b,"b",7,3);
  37.             a_callfunc("selection",4);
  38. /* 004 */   selection(b,7);
  39.                a_endfunc("sel_control",5);
  40. /* 005 */ }
  41.  
  42. NB. Only the algorithm operations want line numbers, NOT the
  43. animation functions or the  #includes.
  44.  
  45. 1.2  User Entry Points
  46.  
  47. You can alter the five user modules (user1.c-user5.c).  When
  48. Calgor is asked to run a user module, it starts at
  49. user#-control(); (where # is the number of the module you are
  50. playing).  It is VERY important that your program should start at
  51. this point and not a point like main().
  52. E.g.
  53.  
  54. /* 001 */ void user1_control(){
  55. /* 002 */   int d[10] = {-1,8,7,6,5,4,3,2,1,0};
  56. /* 003 */   int parts = 10;
  57.             a_func("user1_control",1);
  58.             a_irayini(d,"d",parts,2);
  59.             a_intini(parts,"parts",3);
  60.             a_show(4);
  61. /* 004 */   quicksortb(d,0,parts-1);
  62.             a_endfunc("user1_control",5);
  63. /* 005 */ }
  64.  
  65. 1.3 Compiling The Project
  66.  
  67. The Calgor.dice file has been included to help you in compiling
  68. the project (calgor.dice is just a make file).  If  you are using
  69. DICE, all you have to do is double click on this icon.  This will
  70. pass the Calgor.dice file to Vmake, just specify your target
  71. machine, and where the code is going to be compiled (these are
  72. first set to RAM:) and then compile as normal.
  73.  
  74. Calgor is set up to be compiled with Workbench 2.0 includes, if
  75. you want to compile under WB 3.0 then define V3, in the
  76. hold/extra.h file (this is presently commented out).
  77.  
  78.  
  79. 2.0 Animation Functions
  80.  
  81. To program an algorithm, so that it can be used by the animation
  82. system is analogous to sequentially describing events taken by
  83. the algorithm.  So with this in mind here are the functions,
  84. their parameters and examples of their operations.
  85.  
  86. 2.1 void a_func(char *,int)
  87.  
  88. char * Function Name
  89. int    HLF
  90.  
  91. This function  is used to signal to the animation system that a
  92. function is starting.
  93.  
  94. E.g.
  95.  
  96. /* Line 000 */ void sel_control(void);
  97.  
  98. /* Line 001 */  void sel_control(void){
  99.                   a_func("sel_control",1);
  100. /* Line 002 */  }
  101.  
  102. It displays the function name in the title bar.  Calling this
  103. function repeatedly with the same function name causes the
  104. function index to increase by one.
  105.  
  106. Caution must be taken if declarations are given after the
  107. function.  E.g.
  108.  
  109. /* Line 000 */ void sel_control(void);
  110.  
  111. /* Line 001 */ void sel_control(void){
  112.                  a_func("sel_control",1);
  113. /* Line 002 */   int a = 1;
  114. /* Line 003 */ }
  115.  
  116.  
  117. This would probably produce a compiler error due to the function
  118. 'a_func' being in front of  the declaration 'int a=1'.  To
  119. correct, specify a_func (or for that any animation function)
  120. after declarations, so the correct method would be.
  121.  
  122. /* Line 000 */ void sel_control(void);
  123.  
  124. /* Line 001 */ void sel_control(void){
  125. /* Line 002 */   int a = 1;
  126.                  a_func("sel_control",1);
  127. /* Line 003 */ }
  128.  
  129.  
  130. 2.2 void a_irayini(int [],char *,int,int)
  131.  
  132. int [] Array
  133. char * Array Name
  134. int    Number Of Elements
  135. int    HLF
  136.  
  137. a_irayini will show the animation sequences to initialise an
  138. integer array.
  139.  
  140. E.g.
  141.  
  142. /* Line 000 */ void sel_control(void);
  143.  
  144. /* Line 001 */ void sel_control(void){
  145. /* Line 002 */   int b[7]={ 12, 13, 11, 9, 14, 15, 16};
  146.                     a_irayini(b,"b",7,2);
  147. /* Line 003 */ }
  148.  
  149. An important restriction is that there is only one integer array
  150. allowed per program, with a maximum of 10 elements.  If the
  151. elements of the array have not be initialised first before
  152. calling this function, the contents of the elements may contain
  153. junk values, which will be displayed.
  154.  
  155.  
  156. 2.3 void a_iraypas(char *,int)
  157.  
  158. char * Array Name
  159. int    HLF
  160.  
  161. Use this function when passing an array to a function.  a_iraypas
  162. needs to be located in the receiving function.  The function has
  163. similar animation sequences to the a_irayini.  E.g.
  164.  
  165. /* Line 000 */ void sel_control(void);
  166. /* Line 001 */ void selection(int [],int);
  167.  
  168. /* Line 002 */  void sel_control(void){
  169. /* Line 003 */  int b[7]={ 12, 13, 11, 9, 14, 15, 16};
  170.                      a_irayini(b,"b",7,3);
  171. /* Line 004 */    selection(b,7);
  172. /* Line 005 */  }
  173.  
  174. /* Line 006 */  void selection(int a[], int N){
  175. /* Line 007 */  int i, j, min, t;
  176.                   a_iraypas("a",6);
  177. /* Line 008 */  }
  178.  
  179.  
  180. 2.4 void a_endfunc(char *,int)
  181.  
  182. char * Function Name
  183. int    HLF
  184.  
  185. This function is used to denote that a function is about to end.
  186. There are presently no animations (except for highlighting) that
  187. go with this function.  It allows the animation system to keep
  188. track of the current function .  E.g.
  189.  
  190. /* Line 000 */ void sel_control(void);
  191.  
  192. /* Line 001 */ void sel_control(void){
  193. /* Line 002 */ int b[7]={ 12, 13, 11, 9, 14, 15, 16};
  194.                     a_endfunc("sel_control",3);
  195. /* Line 003 */ }
  196.  
  197.  
  198. 2.5 void a_intini(int, char *,int)
  199.  
  200. int    Integer value
  201. char * Integer Name
  202. int    HLF
  203.  
  204. The function a_intini causes the animation which shows the
  205. variables initial value.  The function takes the integer value,
  206. name and HLF. E.g.
  207.  
  208. /* Line 000 */ void sel_control(void);
  209.  
  210. /* Line 001 */ void sel_control(void){
  211. /* Line 002 */   int anumber=1;
  212.                     a_intini(anumber,"anumber",2);
  213. /* Line 003 */ }
  214.  
  215. If a variable has not been initialised then a junk value could be
  216. shown.  This  should only be used once usually at the
  217. beginning of the function. When assigning a new value to a
  218. variable use the a_intass function.
  219.  
  220.  
  221.  
  222. 2.6 void a_intass(int, char *, char *,int)
  223.  
  224. int    Value To Assign,
  225. char * Destination Value,
  226. char * Source Value,
  227. int    HLF.
  228.  
  229. When assigning values to integer variables use a_intass.  The
  230. source value can be arithmetic sum (9+1*2+a[9]-v), absolute value
  231. (10), variable (v), array with an integer index(a[10]), array
  232. with a variable (a[v]), array with variable with integer offset
  233. (a[v*1]).
  234.  
  235. Limitations:
  236.  
  237. 1).  Full evaluation of the arithmetic expression in the array
  238.      delimeters is not made so (a[v+1*2]) would not be evaluated
  239.      properly, also (a[1+v]) would be evaluated incorrectly.
  240. 2).  Only *, -, / and + operations are evaluated.
  241. 3).  There is no precedence ordering so the sum (9+1*2) would
  242.      equal 20 and not 18.
  243. 4).  a_intass cannot handle bracketed expressions such as (8+9)*7
  244.      .
  245. 5).  The maximum number of components in a sum is 10.
  246.  
  247. The destination value can either be an integer variable (v),
  248. integer array indexed by an integer (v[10]) or an integer array
  249. indexed by a  integer variable (v[v]).
  250.  
  251. /* Line 000 */ void sel_control(void);
  252.  
  253. /* Line 001 */ void sel_control(void){
  254. /* Line 002 */   int anum=1;
  255. /* Line 003 */   int morn=9;
  256.                  a_intini(anum,"anum",2);
  257.                        a_intini(morn,"morn",3);
  258. /* Line 004 */   anum = 4 + morn* 5;
  259.                  a_intass("anum","4+morn+5",4);
  260. /* Line 005 */ }
  261.  
  262. a_intass should usually be placed after the sum has been executed
  263. in the algorithm, however the animation player does keep an
  264. internal representation of values.  It is possible therefore to
  265. place the a_intass before the actual sum has been executed and
  266. have the animation system display the correct answer according to
  267. the sum E.g.
  268.  
  269. /* Line 000 */ void sel_control(void);
  270.  
  271. /* Line 001 */ void sel_control(void){
  272. /* Line 002 */   int anum=1;
  273. /* Line 003 */   int morn=9;
  274.                  a_intini(anum,"anum",2);
  275.                  a_intini(morn,"morn",3);
  276.                  a_intass("anum","4*morn+5",4);
  277. /* Line 004 */   anum = 4 + morn * 5;
  278. /* Line 005 */ }
  279.  
  280. /* This example would start the assignment animation sequences
  281. with anumber being assigned the value of  41 */
  282.  
  283.  
  284. 2.7 void a_intcomp(char *,int)
  285.  
  286. char * Evaluation expression
  287. int    HLF
  288.  
  289. This function will start the animation sequences for comparing
  290. two integer expressions.  The function cannot handle more than
  291. two expressions but can handle the following operators:
  292.  
  293. >, <, <=, >=, == , !=, as well as the unary test i.e.
  294. (expression).
  295.  
  296. The two expressions can either be an arithmetic sum
  297. (9+1*2+a[9]-v), an absolute value (10), a variable (v), an array
  298. with an integer index(a[10]), array with a variable (a[v]), or
  299. array with variable with integer offset (a[v*1]).
  300.  
  301. E.g.
  302.  
  303. /* Line 000 */ void sel_control(void);
  304.  
  305. /* Line 001 */ void sel_control(void){
  306. /* Line 002 */   int anum=1;
  307. /* Line 003 */   int morn=9;
  308.                  a_intini(anum,"anum",2);
  309.                  a_intini(morn,"morn",3);
  310.                  a_intcomp("morn > anum",4);
  311. /* Line 004 */   if (morn >  anum)
  312. /* Line 005 */     anum =0 ;
  313. /* Line 006 */ }
  314.  
  315. Notice that a_intcomp is called before the actual comparison is
  316. made in the algorithm, it is legal to do this as a_intcomp relies
  317. on the internal values of variables for its operation.
  318.  
  319.  
  320. 2.8 void a_show(int)
  321. int HLF
  322.  
  323. This function is simply used to highlight a line, used so you can
  324. monitor program steps.  E.g.
  325.  
  326. /* Line 000 */ void sel_control(void);
  327. /* Line 001 */ void selection(int [],int);
  328. /* Line 002 */ void sel_control(void){
  329. /* Line 003 */ int b = 0;
  330.                  a_show(4);
  331. /* Line 004 */   selection(b,7);
  332. /* Line 005 */ }
  333.  
  334. Note that the function is called before the calling of
  335. selection(b,7), if it was placed after,  the highlight would not
  336. represent the correct program sequence.
  337.  
  338.  
  339. 3.0 Loops
  340.  
  341. Just a few pointers, when executing a for loop an assignment is
  342. made once only in the first part of the loop, a comparison is
  343. made before the loop is entered and a value is  changed.  To
  344. observe these effects call a_intass and a_intcomp (respectively)
  345. before entering the loop.  When inside the loop call the a_intass
  346. routine and then call a_intcomp  E.g.
  347.  
  348. /* Line 000 */ void sel_control(void);
  349. /* Line 001 */ void selection(int [],int);
  350. /* Line 002 */ void sel_control(void){
  351. /* Line 003 */ int b = 0;
  352. /* Line 004 */ int a = 9;
  353.                  a_intini(b,"b",3);
  354.                  a_intini(a,"a",4);
  355.                  a_intass("b","0",5);
  356.                  a_intcomp("b < a",5);
  357. /* Line 005 */   for(b=0;b < a; b++){
  358.                     a_intass("b","b + 1",5);
  359.                     a_intcomp("b < a",5);
  360. /* Line 006 */   }
  361.  
  362. /* Line 007 */   selection(b,7);
  363. /* Line 008 */ }
  364.  
  365. Happy Programming
  366.